feat(multiagent): add FunctionNode to improve DX for deterministic cases #991

dbschmigelski · 2025-10-06T22:34:45Z

Description

In our docs we call out a Custom Node Type which can be used to implement deterministic nodes. But this requires customers to know about stop_reason and construct the DEEPLY nested return type of MultiAgentResult which uses NodeResult which uses AgentResult - this is too in the weeds in my opinion.

To improve developer experience, we will vend a FunctionNode which handles the hard part.

new DX

def deterministic_function(task, invocation_state=None, **kwargs):
    ...



# Create nodes
agent = Agent()
function_node = FunctionNode(deterministic_function, "deterministic_function")
# Build graph
builder = GraphBuilder()
builder.add_node(agent, "agent")
builder.add_node(function_node, "deterministic_function")

The alternative here is to vend an abstract class. I am on the fence about this. An abstract class feels more "correct" but the DX of simply providing the method feels easiest to me. Very open to discussing.

Related Issues

N/A

Documentation PR

pending

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

I ran hatch run prepare

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

src/strands/multiagent/function_node.py

Unshure

Agree with the devex of this approach, it is very clean. As for a abstract class, I think we can migrate to that if customers want it in the future, but good with this for now.

Unshure · 2025-10-07T17:00:30Z

src/strands/multiagent/function_node.py

+        logger.debug("function_name=<%s> | executing function", self.name)
+
+        start_time = time.time()
+        span = self.tracer.start_multiagent_span(task, "function_node")


Not sure if we should be using this to record a function node:

sdk-python/src/strands/telemetry/tracer.py

Line 622 in 776fd93

def start_multiagent_span(

Why? We use it in both swarm and graph with the name of the node?

https://github.com/search?q=repo%3Astrands-agents%2Fsdk-python%20start_multiagent_span&type=code

Huh, I flagged this because we are setting a field in this function named gen_ai.agent.name, and this is almost always not an agent. We should probably revisit how we do this in the other multi-agent cases, but not a blocker for this pr

sdk-python/src/strands/telemetry/tracer.py

Line 662 in 26862e4

"gen_ai.agent.name": instance,

Ahh sorry misunderstood the callout.

Looking at it now, honeslty use of gen_ai.agent.name seems inappropriate for graph and swarm too at the top level. It seems like these should all be using gen_ai.operation.name.

So I guess we can

Keep gen_ai.agent.name for consistency

Remove entirely until we need to add back

introduce a start_multiagent_function_node_span

I'm leaning towards 1 for consistency, seems like you are too if I'm not mistaken

Lets not block this pr, im fine with keeping it consistent for now. But lets create an issue to track the proper fix of this

src/strands/multiagent/function_node.py

tests_integ/test_multiagent_function_node.py

src/strands/multiagent/function_node.py

tests/strands/multiagent/test_function_node.py

codecov · 2025-10-10T15:02:32Z

Codecov Report

❌ Patch coverage is 97.87234% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/multiagent/function_node.py	97.82%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

STYLE_GUIDE.md

mkmeral · 2025-10-29T14:30:02Z

src/strands/multiagent/function_node.py

+
+    def __call__(
+        self, task: str | list[ContentBlock], invocation_state: dict[str, Any] | None = None, **kwargs: Any
+    ) -> str | list[ContentBlock] | Message:


is there any way we can provide more flexibility here? This essentially gets them to write MultiAgentBase. I'd rather they return string or something serializable, and we adjust accordingly

They can return a string though if they want? I added the | list[ContentBlock] | Message because I thought that was more flexible if you want to do more advanced things

mkmeral · 2025-10-29T14:32:55Z

src/strands/multiagent/function_node.py

+        """
+        self.func = func
+        self.name = name
+        self.tracer = get_tracer()


TODO for later probably: streaming callables 😅 #961

Good point let me take a look for the streaming

feat(multiagent): add FunctionNode to improve DX for deterministic cases

838c236

dbschmigelski had a problem deploying to auto-approve October 6, 2025 22:34 — with GitHub Actions Failure

dbschmigelski commented Oct 6, 2025

View reviewed changes

src/strands/multiagent/function_node.py Show resolved Hide resolved

dbschmigelski had a problem deploying to auto-approve October 6, 2025 22:42 — with GitHub Actions Failure

dbschmigelski marked this pull request as ready for review October 6, 2025 22:49

Unshure reviewed Oct 7, 2025

View reviewed changes

comments

709ef4b

dbschmigelski had a problem deploying to auto-approve October 7, 2025 21:50 — with GitHub Actions Failure

pgrayy reviewed Oct 9, 2025

View reviewed changes

tests_integ/test_multiagent_function_node.py Show resolved Hide resolved

pgrayy approved these changes Oct 9, 2025

View reviewed changes

JackYPCOnline reviewed Oct 9, 2025

View reviewed changes

src/strands/multiagent/function_node.py Show resolved Hide resolved

pgrayy previously approved these changes Oct 9, 2025

View reviewed changes

dbschmigelski dismissed pgrayy’s stale review via c4b0610 October 9, 2025 15:26

dbschmigelski temporarily deployed to auto-approve October 9, 2025 15:27 — with GitHub Actions Inactive

JackYPCOnline previously approved these changes Oct 9, 2025

View reviewed changes

zastrowm previously approved these changes Oct 9, 2025

View reviewed changes

comments

4b9b2f5

dbschmigelski dismissed stale reviews from zastrowm and JackYPCOnline via 4b9b2f5 October 10, 2025 15:00

dbschmigelski force-pushed the function-node branch from c4b0610 to 4b9b2f5 Compare October 10, 2025 15:00

dbschmigelski temporarily deployed to auto-approve October 10, 2025 15:00 — with GitHub Actions Inactive

Unshure previously approved these changes Oct 19, 2025

View reviewed changes

Update STYLE_GUIDE.md

f690084

dbschmigelski dismissed Unshure’s stale review via f690084 October 23, 2025 20:07

dbschmigelski temporarily deployed to auto-approve October 23, 2025 20:07 — with GitHub Actions Inactive

Update STYLE_GUIDE.md

5fc0259

dbschmigelski had a problem deploying to auto-approve October 23, 2025 20:08 — with GitHub Actions Failure

dbschmigelski temporarily deployed to auto-approve October 27, 2025 19:30 — with GitHub Actions Inactive

JackYPCOnline reviewed Oct 27, 2025

View reviewed changes

STYLE_GUIDE.md Outdated Show resolved Hide resolved

Update STYLE_GUIDE.md

504a211

github-actions bot added the size/m label Oct 28, 2025

dbschmigelski temporarily deployed to auto-approve October 28, 2025 13:50 — with GitHub Actions Inactive

Update STYLE_GUIDE.md

00b5632

github-actions bot added size/m and removed size/m labels Oct 28, 2025

dbschmigelski had a problem deploying to auto-approve October 28, 2025 13:51 — with GitHub Actions Failure

dbschmigelski temporarily deployed to auto-approve October 28, 2025 13:56 — with GitHub Actions Inactive

Unshure approved these changes Oct 29, 2025

View reviewed changes

dbschmigelski mentioned this pull request Oct 29, 2025

[BUG] gen_ai.agent.name OTel attribute used for MultiAgent spans even when an "agent" may not be used #1105

Open

poshinchen approved these changes Oct 29, 2025

View reviewed changes

mkmeral reviewed Oct 29, 2025

View reviewed changes

feat(multiagent): add FunctionNode to improve DX for deterministic cases #991

Are you sure you want to change the base?

feat(multiagent): add FunctionNode to improve DX for deterministic cases #991

Uh oh!

Conversation

dbschmigelski commented Oct 6, 2025 • edited by zastrowm Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issues

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

Uh oh!

Unshure left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Unshure Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Unshure Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Oct 10, 2025

Codecov Report

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

dbschmigelski commented Oct 6, 2025 •

edited by zastrowm

Loading

Unshure Oct 19, 2025 •

edited

Loading

Unshure Oct 29, 2025 •

edited

Loading